Python is the most popular first language for programmers on a Mac.
Until recently, the language's lack of standard development tooling, plus competing optional-but-essential development tools, meant a rocky start for Python beginners.
To cut through the confusion, I'll show you an up-to-date approach to install Python and set up a programming project, using a single tool named Rye, to install Python versions and software libraries.
Rye is an all-in-one project management tool for Python, written in Rust (for speed) and inspired by Cargo, Rust's comprehensive package manager, from Armin Ronacher, the creator of the Python web framework Flask. It's ideal for beginners, borrowing a folder-based approach to development from other languages such as JavaScript and Ruby.
Contents
You'll want to save the URL for this guide for future reference. Here's what is covered here:
- Before You Get Started
- Python Installation with Rye
- Check for Python
- Install Rye
- Set the PATH for Rye
- Verify Rye installation
- Verify Python installation
- Version and Package Management with Rye
- Create a project with Rye
- Set a version
- Add packages
- Sync to set up the project
- Run Python
- Python Workflow with Rye
- Conclusion
Before You Get Started
You'll need a terminal application, either Mac Terminal or an alternative such as Warp Terminal (a tool I call, "the fastest way to become a command-line power user").
Before you get started, check if you need to update macOS.
You may have heard that Python is pre-installed on your Mac. Older Macs (prior to macOS 12.3) came with Python 2.7. That's an older version, not the Python 3 that you need. Newer Macs don't come with a pre-installed Python.
You'll need to install Xcode Command Line Tools before you begin programming on a Mac. You should check if Xcode Command Line Tools are installed before you proceed further. When you install Xcode Command Line Tools, Apple includes Python 3.9.6. You might be tempted to use it but that's an older version, intended only for system software, which is why you should install a new version of Python, as shown here.
Python Installation with Rye
There are several ways to set up Mac Python. Here are your options, in a nutshell, with a critique.
On the Python.org website, there's an installer application for the most recent Python version. Most Python developers avoid using it because it clutters a Mac in ways that are difficult to manage.
If you install Homebrew for software development, it's easy to "brew install python." However, the Homebrew-installed Python is not well-suited to managing multiple Python projects and development can be cumbersome.
Some tutorials suggest to install Pyenv, a Python version manager. Pyenv is a good choice for managing multiple Python versions, but it requires familiarity with Pip, a package manager, and Venv or Virtualenv, environment managers. Multiple tools make development more complex.
I recommend installing Python with Rye. With this all-in-one tool, you'll manage multiple Python versions, set up project-based environments, and install Python packages without dependency conflicts. I'll show you how to install Python using Rye, the easy way, with a self-install script.
Check for Python
It's best to start with no previous Python version installed, except for the Python version installed by Xcode Command Line Tools.
Try python3 --version
and which -a python3
to check if Python was installed with Xcode Command Line Tools:
$ python3 --version
Python 3.9.6
$ which -a python3
/usr/bin/python3
You won't use the Python installed by Xcode Command Line Tools, but it's important to know that Xcode Command Line Tools is already there. Otherwise, install Xcode Command Line Tools.
Check if another version of Python is already installed:
$ python --version
zsh: command not found: python
You'll see zsh: command not found: python
if Python is not available. I've written elsewhere about how to update Python if you think you already have Python, as well as a guide to resolving the error "command not found: python" if you are sure Python is installed but not available.
If you have more than one version of Python installed, it's not a problem because you'll set the Mac PATH after installing Rye to make the correct Python version available.
Install Rye
Homebrew is not needed. Rye has a self-install script so you can install Rye with a curl
command.
$ curl -sSf https://rye.astral.sh/get | bash
Curl is a command-line tool that makes HTTP requests from the terminal, useful for tasks like downloading and running installation scripts.
$ curl -sSf https://rye.astral.sh/get | bash
This script will automatically download and install rye (latest) for you.
####################################################################### 100.0%
Welcome to Rye!
This installer will install rye to /Users/username/.rye
This path can be changed by exporting the RYE_HOME environment variable.
Details:
Rye Version: 0.26.0
Platform: macos (aarch64)
? Continue? (y/n)
Enter y
to continue. Rye will ask questions to customize the installation.
? Select the preferred package installer ›
❯ uv (fast, recommended)
pip-tools (slow, higher compatibility)
By default, Rye offers uv
, a faster and newer package installer. I recommend choosing pip-tools
for compatibility. If you're a beginner, it will be easier to follow tutorials that refer to pip
. Select pip-tools
with the arrow keys.
Next, the self-installer asks which Python version you'll use as a default, offering the Rye-installed version or previously-installed versions.
? What should running `python` or `python3` do when you are not inside a Rye managed project? ›
❯ Run a Python installed and managed by Rye
Run the old default Python (provided by your OS, pyenv, etc.)
It's best to use the Rye-installed version. Accept the default Run a Python installed and managed by Rye
by pressing "Enter". Then the self-installer asks which Python version to install as a default.
? Which version of Python should be used as default toolchain? (cpython@3.12) ›
Accept the default and Rye will install the latest Python version. Installation begins when you press "Enter."
Installed binary to /Users/username/.rye/shims/rye
Bootstrapping rye internals
Downloading cpython@3.12.1
Checking checksum
Unpacking
Downloaded cpython@3.12.1
Updated self-python installation at /Users/username/.rye/self
The rye directory /Users/username/.rye/shims was not detected on PATH.
It is highly recommended that you add it.
? Should the installer add Rye to PATH via .profile? (y/n) ›
Notice that Rye installs its Python files to ~/.rye/shims/rye
.
Rye offers to set the $PATH
to give precedence to its Python version by modifying the .profile
file.
Use of the .profile
file is a Linux convention. On the Mac, it's preferred to set the $PATH
in .zprofile
or .zshrc
files, preferably .zprofile
. Enter n
to skip this automatic step. Later, you'll set the $PATH
manually.
✔ Should the installer add Rye to PATH via .profile? · no
note: did not manipulate the path. To make it work, add this to your .profile manually:
source "$HOME/.rye/env"
To make it work with zsh, you might need to add this to your .zprofile:
source "$HOME/.rye/env"
For more information read https://rye.astral.sh/guide/installation/
All done!
Rye explains how to complete the installation manually by editing the .zprofile
file. I'll show you how do it.
Set the PATH for Rye
There's one final important step before Rye works correctly. You must set the Mac PATH to make sure Rye finds the correct Python version. Otherwise, entering the command python
will trigger zsh: command not found: python
and the command python3
will access the older Xcode-installed Python version.
Edit the ~/.zprofile
file. The ~/.zprofile
file is used for setting the $PATH
. Alternatively, you can modify the ~/.zshrc
file (see How Do Zsh Configuration Files Work? for an explanation of the differences). You can use TextEdit, the default macOS graphical text editor, opening a file from the terminal:
$ open -e ~/.zprofile
You also can use the command line editors nano
or vim
to edit the shell configuration files. See Zsh Shell Configuration for more about editing shell configuration files.
Add this command as the last line of your configuration file to configure the Z shell for Rye:
source "$HOME/.rye/env"
When your terminal session starts, Z shell will run the ~/.rye/env
script to set shims to intercept and redirect any Python commands. You'll need double quotes because the command contains special characters.
Rye adds the shims to your $PATH
so that running the command python
or python3
will run a Rye-installed Python version.
Changes to the ~/.zprofile
file will not take effect in the Terminal until you've quit and restarted the terminal. Alternatively (this is easier), you can use the source
command to reset the shell environment:
$ source ~/.zprofile
The source
command reads and executes a shell script file, in this case resetting the shell environment with your new $PATH
setting.
After resetting your shell, you can check the $PATH
setting.
$ echo $PATH
/Users/username/.rye/shims:/opt/homebrew/bin:/opt/homebrew/sbin:/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/System/Cryptexes/App/usr/bin:/usr/bin:/bin:/usr/sbin:/sbin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/local/bin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/bin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/appleinternal/bin
The ~/.rye/shims
directory should be leftmost, taking precedence over other directories.
Verify Rye installation
After installing Rye, use rye --version
to verify that it has been installed.
$ rye --version
rye 0.26.0
commit: 0.26.0 (d245f625e 2024-02-23)
platform: macos (aarch64)
self-python: cpython@3.12
symlink support: true
uv enabled: false
Verify Python installation
Check that Python is available:
$ python --version
Python 3.12.1
Yay! You've installed Python. If you see zsh: command not found: python
, check that the Mac PATH is set correctly.
The python3
command should give you the Rye-installed version, not the Xcode-installed version.
$ python3 --version
Python 3.12.1
The which
command shows the Rye shims directory when you try to see where Python is installed. Keep in mind that you've set the ~/.zprofile
file to use Rye shims to intercept the python
command and deliver the Rye-installed versions.
$ which python
/Users/username/.rye/shims/python
You've successfully installed Python with Rye.
Version and Package Management with Rye
You can use Rye to:
- Set up a Python project.
- Install a specific Python version for a project.
- Install Python packages for the project.
Other languages adopt a project-based approach to package management (for example, Rust's Cargo, Ruby's Bundler, and JavaScript's npm). Python has been slow to adopt this approach, but Rye is changing that, eliminating the need for separate tools such as Pyenv, Pip, and Venv for managing versions, software libraries, and environments.
With Rye, you'll start by creating a new project and choosing a Python version. You can then install packages for that project. Rye will manage the Python version and packages for you.
Create a project with Rye
Make a folder for a Python project. Then change directories to the project root:
$ mkdir myproject
$ cd myproject
Specify a Python version for your project:
$ rye pin 3
pinned 3.12.1 in /Users/username/workspace/myproject/.python-version
The command rye pin 3
will create a .python-version
file specifying the newest Python version for your project.
You must run the command rye init
to create a pyproject.toml
file in your project root directory. This is a project-specific configuration file that Rye uses to manage Python versions and packages.
$ rye init
success: Initialized project in /Users/username/workspace/myproject/.
Run `rye sync` to get started
Now you can fetch a Python version and install packages.
Set a version
Rye can install and switch among different Python versions.
Rye uses the term "toolchains" to refer to installed Python versions. To install a Python version, you can fetch a toolchain using Rye.
$ rye fetch
$
If you've specified the default Python with rye pin
, rye fetch
does nothing. If you specified a different Python version, rye fetch
will install the specified version.
$ rye fetch
Downloading cpython@3.12.1
Checking checksum
success: Downloaded cpython@3.12.1
By default, Rye installs all Python executables in a hidden folder in your user home directory ~/.rye/py/
. The Rye shims in the Mac $PATH
will select the correct Python version you've specified in your project directory,
Add packages
Package managers allow you to download, install, and update software libraries and their dependencies. Most packages depend on other external software libraries—the package manager will fetch and install any dependencies required by that package.
Experienced Python developers are familiar with Pip, the standard package manager for Python, included with any version of Python since Python 3.3.
The command pip install
installs packages "globally" into a system Python or shared Python versions, creating potential conflicts.
To safely install Python packages for a specific project with pip
, you have to use a Python environment manager such as Venv to create and activate a virtual environment to avoid dependency conflicts.
When you use Rye as an all-in-one tool, you won't need venv
for environment management, installing packages directly with Rye.
Before you try to install a package with Rye, be sure you've created a pyproject.toml
file in your project root directory with rye init
.
You can install any Python package from the Python Package Index. Here we'll install the cowsay utility.
$ rye add cowsay
Added cowsay>=6.1 as regular dependency
If you see error: did not find pyproject.toml
, you need to run rye init
.
Sync to set up the project
Before you can use a package in a Rye project, you must run rye sync
to update lockfiles and install the dependencies into the virtual environment.
$ rye sync
Initializing new virtualenv in /Users/username/workspace/python/myproject/.venv
Python version: cpython@3.12.3
Generating production lockfile: /Users/username/workspace/python/myproject/requirements.lock
Creating virtualenv for pip-tools
Generating dev lockfile: /Users/username/workspace/python/myproject/requirements-dev.lock
Installing dependencies
Looking in indexes: https://pypi.org/simple/
Obtaining file:///. (from -r /var/folders/ls/g23m524x5jbg401p12rctz7m0000gn/T/tmp06o05xiq (line 2))
Installing build dependencies ... done
Checking if build backend supports build_editable ... done
Getting requirements to build editable ... done
Installing backend dependencies ... done
Preparing editable metadata (pyproject.toml) ... done
Collecting cowsay==6.1 (from -r /var/folders/ls/g23m524x5jbg401p12rctz7m0000gn/T/tmp06o05xiq (line 1))
Using cached cowsay-6.1-py3-none-any.whl.metadata (5.6 kB)
Using cached cowsay-6.1-py3-none-any.whl (25 kB)
Building wheels for collected packages: myproject
Building editable for myproject (pyproject.toml) ... done
Created wheel for myproject: filename=myproject-0.1.0-py3-none-any.whl size=1074 sha256=0b34a41cbb517a78e5b60593c75e93a37df0bf7958e8921be5f6f6e24a26b5d1
Stored in directory: /private/var/folders/ls/g23m524x5jbg401p12rctz7m0000gn/T/pip-ephem-wheel-cache-m03jgkok/wheels/8b/19/c8/73a63a20645e0f1ed9aae9dd5d459f0f7ad2332bb27cba6c0f
Successfully built myproject
Installing collected packages: myproject, cowsay
Successfully installed cowsay-6.1 myproject-0.1.0
Done!
Rye displays all its operations but you don't have to read all the details.
Run Python
After installing a package and running rye sync
, you can use the Python interpreter interactively (the REPL or Read-Eval-Print Loop).
$ python
Python 3.12.1 (main, Jan 7 2024, 23:31:12) [Clang 16.0.3 ] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import cowsay
>>> cowsay.cow('Hello World')
___________
| Hello World |
===========
\
\
^__^
(oo)\_______
(__)\ )\/\
||----w |
|| ||
>>>
Enter quit()
or type Control + D
to exit the Python interpreter.
Now you're ready to develop any Python project with Rye! You can read the Rye User Guide to learn more.
Python Workflow with Rye
As you code in Python, you'll want to add software libraries to your project. Let's look at an example.
Requests is an HTTP library that you'll likely use in many projects. If you visit the Requests page on PyPI, you'll see the installation instructions:
$ python -m pip install requests
The python -m pip
command is a bit cumbersome, and if you use Pip, you have to precede it with python -m venv .venv
(to set up a virtual environment) and source .venv/bin/activate
(to activate a virtual environment).
With Rye, you can add Requests to your pyproject.toml
file.
$ rye add requests
Then run rye sync
to install the package.
$ rye sync
Now you can use the Requests library in your Python project, including it with an import
statement.
Remember, when you see pip install
in a tutorial, you can use rye add
and rye sync
instead, without additional commands for a virtual environment.
Beginners using pip install often encounter headaches with command not found: pip and error: externally-managed-environment. Rye eliminates these problems.
Conclusion
This article is based on a guide that offers additional details about how to install Python on Mac.
Rye is the new favorite for installing and managing Python because it offers a single coherent setup and packaging system, eliminating the need for separate tools such as Pyenv, Pip, and Venv for managing versions, software libraries, and environments.
Python is the first programming language for most beginners. As it grows in popularity for machine learning and data science, you'll want Python on your Mac for many of the tutorials you'll find on freeCodeCamp.